home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Programming / MiniGL / doc / Functions < prev   
Encoding:
Text File  |  2000-04-07  |  9.9 KB  |  291 lines
  1. API description
  2. ---------------
  3.  
  4. Here's a short outline of the API. As it's OpenGL(tm) compatible,
  5. only the differences to this API is outlined. If in doubt, have a
  6. look at the source code and the demos. Sorry if this is not really
  7. worth to be called "documentation", but our time right now is too
  8. tight to work on anything larger.
  9.  
  10. The following functions are implemented:
  11.  
  12. glAlphaFunc            glFrontFace              glScaled            glNormal3f
  13. glBegin                glFrustum                glScalef            glTexEnvi
  14. glEnd                  glGenTextures            glScissor           glTexEnvf
  15. glTexGeni              glGetError               glShadeModel        glTexEnviv
  16. glBindTexture          glGetString              glTexCoord2f        glTexEnvfv
  17. glBlendFunc            glHint                   glTexCoord2fv       glTexParameteri
  18. glClear                glLoadIdentity           glTexImage2D        glTexParameterf
  19. glClearColor           glLoadMatrixf            glTexSubImage2D     glTexParameteriv
  20. glClearDepth           glLoadMatrixd            glTranslated        glTexParameterfv
  21. glColorTable           glMatrixMode             glTranslatef
  22. glCullFace             glMultMatrixd            glViewport
  23. glDeleteTextures       glMultMatrixf            glVertex4f
  24. glDepthFunc            glOrtho                  glVertex2f
  25. glDepthMask            glPixelStorei            glVertex2i
  26. glEnable               glPixelStoref            glVertex3f
  27. glDisable              glPolygonMode            glVertex3fv
  28. glDrawBuffer           glPushMatrix             glDepthRange
  29. glFinish               glPopMatrix              glColor4f
  30. glFlush                glReadPixels             glColor4fv
  31. glFogf                 glRotated                glColor3f
  32. glFogfv                glRotatef                glColor3fv
  33. glFogi                                          glColor4ub
  34.                                                 glColor4ubv
  35.                                                 glColor3ub
  36.                                                 glColor3ubv
  37.  
  38.  
  39. gluLookAt
  40. gluPerspective
  41.  
  42.  
  43. These functions are more or less compatible. You  should  have  a
  44. look at the source code for determining what's really supported.
  45.  
  46.  
  47.  
  48. These functions are MiniGL specific:
  49.  
  50. void MGLInit()
  51. void MGLTerm()
  52.     MGLInit should be the first MiniGL function called, while MGLTerm should be the last.
  53.     They Open/Close required libraries...
  54.  
  55.  
  56.  
  57. void *mglCreateContext(int offx, int offy, int w, int h);
  58.  
  59.     This function creates a rendering context for MiniGL. Currently, there can be only
  60.     one context per application.
  61.  
  62.     offx, offy - currently ignored, set to 0 for future compatibility.
  63.     w,h        - dimensions of the display to be opened.
  64.  
  65.     The function returns 0 if it failed, and non-zero if successfull. The return value
  66.     is a pointer to the created context, which is private, and currently of no use, anyway.
  67.  
  68.  
  69.  
  70. void * mglCreateContextFromID(GLint id, GLint *w, GLint *h);
  71.  
  72.     This function creates a context, with id being a valid display mode for Warp3D.
  73.  
  74.     id  - display mode (see mglGetSupportedScreenModes for obtaining it). It's either
  75.           an Amiga display mode, MGL_SM_WINDOWMODE (indicating "use window mode"), or
  76.           MGL_SM_BESTMODE (indicating "use best mode").
  77.     w,h - pointers to variables that are fille with the actual dimensions of the display.
  78.  
  79.     The functions return value are equal to that of mglCreateContext.
  80.  
  81.  
  82.  
  83. void mglDeleteContext();
  84.  
  85.     Deletes a context previously created by mglCreateContex/mglCreateContextFromID.
  86.  
  87.  
  88.  
  89. void mglResizeContext(GLsizei width, GLsizei height);
  90.  
  91.     Resize the drawing area. The screen is closed and opened again with the
  92.     new dimension.
  93.     Note: This function currently only resizes a full screen context.
  94.  
  95.     width, height - new dimensions for the display.
  96.  
  97.  
  98.  
  99. void mglEnableSync(GLboolean enable);
  100.  
  101.     Enables or disables vertical syncing of the display.
  102.  
  103.     enable - either GL_TRUE, or GL_FALSE.
  104.  
  105.     This function takes effect immediatly, and can be called before or after creating
  106.     of the context.
  107.  
  108.  
  109.  
  110. void mglWriteShotPPM(char *filename);
  111.  
  112.     Write the contents of the current front buffer to a PPM file.
  113.  
  114.     filename - name of the file to write to.
  115.  
  116.  
  117.  
  118. void mglTexMemStat(GLint *Current, GLint *peak);
  119.  
  120.     This functions requests information about the texture memory usage.
  121.  
  122.     Current - pointer to a GLint that will be filled with the amount of texture
  123.               memory currently in use.
  124.     Peak    - pointer to a GLint that will be filled with the highest amount of
  125.               texture memory that was allocated at one time.
  126.  
  127.  
  128.  
  129. GLboolean mglLockDisplay(void);
  130.  
  131.     This function locks the hardware for rendering, and must be called before
  132.     rendering anything. This function is not needed if the lock mode is set
  133.     to SMART (see the discussion of mglLockMode for an explanation).
  134.  
  135.     The return value is a GLboolean, with GL_TRUE meaning the lock has succeeded,
  136.     and GL_FALSE otherwise.
  137.  
  138.  
  139.  
  140. void mglUnlockDisplay(void);
  141.  
  142.     A lock obtained with mglLockDisplay or mglLockBack (see below) must be released
  143.     once the frame is finished. mglUnlockDisplay will take care of that. Note that
  144.     it is safe to call this function without a lock, or with SMART lock enabled.
  145.  
  146.  
  147.  
  148. GLboolean mglLockBack(MGLLockInfo *info);
  149.  
  150.     Gives access to the back buffer. The structure pointed to by info is fille with the
  151.     appropriate values, and GL_TRUE is return when the lock succeeded, GL_FALSE otherwise.
  152.     If the current lock mode (see mglLockMode) is MANUAL, you'll have to unlock yourself.
  153.  
  154.     info - pointer to a structure to be filled (see include/mgl/modes.h)
  155.  
  156.  
  157.  
  158. void mglLockMode(GLenum lockMode);
  159.  
  160.     Defines the way display locking is done. Currently, there are two mechanisms:
  161.     MGL_LOCK_MANUAL - You must perform locking yourself (see mglLockDisplay/mglUnlockDisplay)
  162.     MGL_LOCK_SMART  - Locking is performed automatically. This is the save method, as the
  163.                       lock is not kept more than 1/20th second. Per-frame-locking may,
  164.                       at higher resolutions, stall the system, possibily causing a dead-lock.
  165.  
  166.     lockMode - one of the above
  167.  
  168.  
  169.  
  170. void mglMainLoop(void);
  171.  
  172.     MiniGL supports a mechanism similar to X or glut: you have a library-provided
  173.     main loop, and define some callback functions that are called on special events.
  174.     This function starts the main loop. It will not terminate, unless mglExit is
  175.     called.
  176.  
  177.     You can set event handlers with the functions mglKeyFunc, mglMouseFunc, and mglIdelFunc.
  178.     To terminate the loop, use mglExit.
  179.  
  180.  
  181.  
  182. void mglKeyFunc(KeyHandlerFn k);
  183.  
  184.     This function sets the key handler function.
  185.  
  186.     k - Pointer to a KeyHandlerFn function. KeyHandlerFn is defined as
  187.         void (*KeyHandlerFn)(char key); The key function will get a Vanilla key
  188.         as it's argument.
  189.  
  190.  
  191.  
  192. void mglMouseFunc(MouseHandlerFn m);
  193.  
  194.     Sets the mouse handler function.
  195.  
  196.     m - Pointer to a MoseHandlerFn. The prototype for the handler function
  197.         is void (*MouseHandlerFn)(GLint x, GLint y, GLbitfield buttons);
  198.  
  199.  
  200.  
  201. void mglIdleFunc(IdleFn *i);
  202.  
  203.     The name is misleading, this function is called every time the main loop
  204.     makes an iteration. This function can be used for displaying one frame.
  205.  
  206.     i - Pointer to a function to be called every frame. The prototype is
  207.         void (*IdleFn)(void);
  208.  
  209.  
  210. void mglExit(void);
  211.  
  212.     Calling this function in any of the callback functions will terminate
  213.     the main loop, causing mglMainLoop to return.
  214.  
  215.  
  216.  
  217. void mglSwitchDisplay(void);
  218.  
  219.     When called, mglSwitchDisplay causes the current drawing area to be made visible.
  220.     Depending on sync state, this function may wait for a vertical blanking
  221.  
  222.  
  223.  
  224.  
  225. void *mglGetWindowHandle(void);
  226.  
  227.     Returns the window handle which is used for rendering. This function provides
  228.     a way for more complicated applications that do not want to use the mglMainLoop
  229.     interface. The window has no IDCMP flags set, use ModifyIDCMP to actually
  230.     get something.
  231.  
  232.     The return value is a struct Window *.
  233.  
  234.  
  235.  
  236. GLint mglGetSupportedScreenModes(MGLScreenModeCallback CallbackFn);
  237.  
  238.     This function can be used to get all available screen modes supported by MiniGL.
  239.     It calls the callback function with every screenmode.
  240.  
  241.     CallbackFn - Pointer to a function for enumerating the screen modes.
  242.                  The function has the following prototype:
  243.                  GLboolean ScreenModeCallback(MGLScreenMode *mode);
  244.                  (The MGLScreenMode is defined in include/mgl/modes.h).
  245.                  mglGetSupportedScreenModes will continue feeding modes to
  246.                  the callback until it runs out of modes, or the callback
  247.                  returns GL_TRUE, indicating it has found a suitable mode.
  248.  
  249.     The return value is the mode id which was accepted by the callback function,
  250.     or MGL_SM_BESTMODE.
  251.  
  252.  
  253.  
  254. void mglChooseWindowMode(GLboolean window_mode);
  255.  
  256.     This function is called before creating a context. It can tell MiniGL to
  257.     open it's display as a window on the workbench.
  258.  
  259.     window_mode - GL_TRUE makes the display a window on the workbench,
  260.                   GL_FALSE opens a screen.
  261.  
  262.  
  263.  
  264. void mglChooseVertexBufferSize(GLint size);
  265.  
  266.     MiniGL doesn't render it's primitives at one. It collects everything between
  267.     glBegin and glEnd, and renders with the glEnd call. The buffer for the
  268.     vertex data is called the vertex buffer. As this is created with the
  269.     context, it must be set before creating it.
  270.  
  271.     size - number of entries in the vertex buffer. Default is 30.
  272.            Set this to a value equal to, or larger than your "longest"
  273.            primitive, i.e. the biggest amount of glVertex calls at between
  274.            glBegin and glEnd.
  275.  
  276.     Example:
  277.  
  278.         glBegin(GL_TRIANGLES);
  279.             glVertex3f(1.0, 1.0, 1.0);
  280.             glColor3f(0.1, 1.0, 0.2);
  281.  
  282.             glVertex3f(1.0, 1.0, 0.0);
  283.             glColor3f(0.1, 1.0, 1.0);
  284.  
  285.             glVertex3f(1.0, 0.0, 1.0);
  286.             glColor3f(0.1, 0.0, 0.2);
  287.         glEnd();
  288.  
  289.         There are three glVertex calls (the glColor calls do not affect this. These
  290.         just set the current vertex's color).
  291.